|
(SST) ShlWAPI.pas Version 1.08 |
|---|---|
| Developer Reference |
| Creates an exact copy of a null-terminated string. |
| Scope |
|---|
| Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas). |
| Syntax | |
|---|---|
 |
function StrDup(pszToDup : LPCSTR) : LPSTR; |
| Parameters | |
|---|---|
| pszToDup [in] | Pointer to, or address of, the null-terminated string to duplicate. Depending on which version of the function is called, this may be either an ANSI (StrDup and StrDupA) or Unicode (StrDupW) string. |
| Return Values |
|---|
| If the function succeeded in allocating the required memory and copying the input/source string, it returns a pointer to the first character of the duplicated string. If the function fails in either, it retruns NIL. |
| Remarks |
|---|
| The function allocates and locks memory on the heap, using the kernel API function LocalAlloc. It is imperative that this memory is freed by the caller, using the Windows API function LocalFree, once the duplicated string is no longer required. |
| The function will also return a valid pointer, even when called with an empty string. |
| StrDup seems to have been introduced in the very first ShlWAPI.dll version (4.71) and continues to be supported up to and including Windows 10. |
| Example |
|---|
| PROCEDURE TForm4.TestShlWAPIStrDup(Sender : TObject); VAR strtoduplicate : STRING; VAR wstrtodup : WideString; VAR apiretptr : POINTER; VAR newinfoline : STRING; BEGIN strtoduplicate := ''; wstrtodup := ''; apiretptr := NIL; newinfoline := ''; strtoduplicate := 'The quick, brown fox jumped over the fence and hid in the fox burrow'; newinfoline := 'StrDup called with pszToDup (without the quotation marks) = "' + strtoduplicate + '"'; Memo1.Lines.Add(newinfoline); apiretptr := StrDup(PChar(strtoduplicate)); IF apiretptr <> NIL THEN BEGIN newinfoline := 'StrDup returned "' + PChar(apiretptr) + '"'; LocalFree(HLOCAL(apiretptr)); END ELSE newinfoline := 'StrDup returned NIL !'; Memo1.Lines.Add(newinfoline); strtoduplicate := ''; newinfoline := 'StrDup called with pszToDup (without the quotation marks) = "" (an empty string)'; Memo1.Lines.Add(newinfoline); apiretptr := StrDup(PChar(strtoduplicate)); IF apiretptr <> NIL THEN BEGIN newinfoline := 'StrDup returned "' + PChar(apiretptr) + '"'; LocalFree(HLOCAL(apiretptr)); END ELSE newinfoline := 'StrDup returned NIL !'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END; |
| When run, the above code produces the following output: |
| StrDup called with pszToDup (without the quotation marks) = "The quick, brown fox jumped over the fence and hid in the fox burrow" StrDup returned "The quick, brown fox jumped over the fence and hid in the fox burrow" StrDup called with pszToDup (without the quotation marks) = "" (an empty string) StrDup returned "" |
| Requirements | |
|---|---|
| Unit: | Declared and imported in (SST)ShlWAPI.pas |
| Library: | (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj |
| Unicode: | Implemented as ANSI (StrDup and StrDupA) and Unicode (StrDupW) functions. |
| Min. ShlWAPI.dll version according to MS SDK doc.: | 4.71 |
| Min. ShlWAPI.dll version based on SST research: | 4.71 |
| Min. OS version(s) according to Microsoft SDK doc.: | Windows 2000, Windows NT 4.0 with Internet Explorer 4.0, Windows 98, Windows 95 with Internet Explorer 4.0 |
| Min. OS version(s) according to SST research.: | Windows NT 4.0 with IE 4.0, Windows 95 with IE 4.0, Windows 98, Windows 2000 and later |
|
Document/Contents version 1.00 Page/URI last updated on 07.12.2023 |
Copyright © Stoelzel Software Technologie (SST) 2010 - 2015 |
Suggestions and comments mail to: webmaster@stoelzelsoftwaretech.com |